/**
 * ITrafficMessageSource.java
 * created: 29.11.2009
 * (c) 2008 by <a href="http://Wolschon.biz">Wolschon Softwaredesign und Beratung</a>
 * This file is part of osmnavigation by Marcus Wolschon <a href="mailto:Marcus@Wolscon.biz">Marcus@Wolscon.biz</a>.
 * You can purchase support for a sensible hourly rate or
 * a commercial license of this file (unless modified by others) by contacting him directly.
 *
 *  osmnavigation is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  osmnavigation is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with osmnavigation.  If not, see <http://www.gnu.org/licenses/>.
 *
 ***********************************
 * Editing this file:
 *  -For consistent code-quality this file should be checked with the
 *   checkstyle-ruleset enclosed in this project.
 *  -After the design of this file has settled it should get it's own
 *   JUnit-Test that shall be executed regularly. It is best to write
 *   the test-case BEFORE writing this class and to run it on every build
 *   as a regression-test.
 */
package org.openstreetmap.travelingsalesman.trafficblocks;

import java.beans.PropertyChangeListener;
import java.io.IOException;
import java.math.BigDecimal;

/**
 * @see TrafficMessageStore#addTrafficMessageSource(ITrafficMessageSource).
 * @author <a href="mailto:Marcus@Wolschon.biz">Marcus Wolschon</a>
 */
public interface ITrafficMessageSource {

    /**
     * ITrafficMessageSource that supports tuning to a radio-station.
     * @author <a href="mailto:Marcus@Wolschon.biz">Marcus Wolschon</a>
     */
    public interface ITunableTrafficMessageSource extends ITrafficMessageSource {

        /**
         * @return the frequency we are currently tuned to in MHz.
         */
        BigDecimal getFrequency();

        /**
         * @param aFrequencyMHz the frequency to tune to in MHz.
         * @throws IOException if we cannot write to the device
         * @throws InterruptedException if our mandatory sleep after sending a command is interrupted
         */
        void setFrequency(final BigDecimal aFrequencyMHz) throws IOException, InterruptedException;

        /**
         * Add a PropertyChangeListener for a specific property.  The listener
         * will be invoked only when a call on firePropertyChange names that
         * specific property.
         * The same listener object may be added more than once.  For each
         * property,  the listener will be invoked the number of times it was added
         * for that property.
         * If <code>propertyName</code> or <code>listener</code> is null, no
         * exception is thrown and no action is taken.
         *
         * @param aPropertyName  The name of the property to listen on. "frequency" or "frequencycode"
         * @param aListener  The PropertyChangeListener to be added
         */

        void addPropertyChangeListener(
                    final String aPropertyName,
                    final PropertyChangeListener aListener);

        /**
         * Remove a PropertyChangeListener from the listener list.
         * This removes a PropertyChangeListener that was registered
         * for all properties.
         * If <code>listener</code> was added more than once to the same event
         * source, it will be notified one less time after being removed.
         * If <code>listener</code> is null, or was never added, no exception is
         * thrown and no action is taken.
         *
         * @param aListener  The PropertyChangeListener to be removed
         */
        void removePropertyChangeListener(
                    final PropertyChangeListener aListener);
    }

    /**
     * The name of the port, file, server,... we
     * are connected to.
     * @return
     */
    public String getPortName();
}
